%  Copyright (C) 2002 Regents of the University of Michigan, portions used with permission 
%  For more information, see http://csem.engin.umich.edu/tools/swmf
\section{Running a Simulation \label{section:running}}

This section describes how to run the stand alone \BATSRUS. 
To run \BATSRUS\ as part of the framework, read the SWMF manual.

As described above, the makefile will help the user to set up a directory
in which to run the main executable.  This directory will have links made to
executables, will have the correct directories for input and output
and will copy the appropriate scripts (if any) for the current machine.
Unfortunately, systems for running the code vary widely.  For example the NASA
Ames SGI Origin and the NCSA SGI Origin have different queuing systems
and therefore require different scripts to run the code. If the
user is running the code on a system which is different than the 
ones listed in section~\ref{section:main_make}, 
he or she will have to create the appropriate
scripts and make the corresponding changes to the makefiles.

\subsection{Before Running the Code \label{section:before_running}}

Before submitting a job or running the code interactively there are
several necessary steps.
\begin{itemize}
\item Use {\tt make} to make the {\tt BATSRUS.exe} executable.
\item Use {\tt make rundir} to make a run directory.
\item Edit the {\tt PARAM.in} file in the {\tt run} directory to contain
      all the important code input (see chapter~\ref{chapter:param}).
\item Check the {\tt PARAM.in} file with the TestParam.pl script.
\item Prepare the proper job script for the users system.
\end{itemize}
To check the parameters in the run/PARAM.in file type
\begin{verbatim}
  ./TestParam.pl
\end{verbatim}
To check another parameter file named run/PARAM.in.other, 
type
\begin{verbatim}
  ./TestParam.pl run/PARAM.in.other
\end{verbatim}
This script reads in the input parameter file and all the
included files and checks that they conform with the 
XML description given in the PARAM.XML 
(or the PARAM.pl file on systems which do not have the 
XML-PARSER::EasyTree Perl package installed).
Error and warnings are printed on the screen. 
If there are no errors the script runs silently.

Before submitting a long job into the queue, it is generally a good idea
to test the code interactively or in a short queue to make sure that
it is working as planned.

\subsection{Interactive Execution \label{section:interactive}}

On most systems, running the code for an extended period of time
on many nodes must happen through a queuing system.  Test runs, however,
can often be done interactively.
Although there is no universal form for running codes under MPI, on a 
number of platforms (e.g. SGI or IRIX and Linux) MPI executables
can be run with the 
\begin{verbatim}
  mpirun -np N BATSRUS.exe
\end{verbatim}
command, where {\tt N} is the number of processors to run the code on.  
On the Cray T3E the command would be
\begin{verbatim}
  mpprun -n N BATSRUS.exe
\end{verbatim}
and for the IBM SP
\begin{verbatim}
  BATSRUS.exe -procs N
\end{verbatim}
For any given system, there will be a limit on the value of {\tt N}
that is allowed in the interactive queue.  {\bf Note that the above two
examples may not work on some systems.}

Many platforms require additional information in a script such as the length 
of time
the run will last, the memory usage, names of error files, and many others.
To run the code, the user typically needs to prepare a script that meets the
system requirements and then submit this script to the queuing system in the 
appropriate way.

\subsection{Queues and Scripts \label{section:queues}}

On most platforms, the code must be run through a queue system because
there are many users that share the resources on a machine.  
The {\tt Scripts/Run}
directory contains scripts for running \BATSRUS\ on the currently recognized 
platforms listed in section~\ref{section:main_make} 
at specific institutions.  For example, the {\tt IRIX64} subdirectory
contains scripts to run on an SGI Origin on machines at The University of
Michigan, NASA Ames  and NCSA.  Even though the user's system is an SGI
Origin, the available scripts may not work for the user's queuing system.
The user will have to develop scripts for his or her specific machine. 
These should be placed in the appropriate subdirectory of {\tt Scripts}.
If either your queuing system or your platform is not recognized you will
have to create a subdirectory and scripts.
The Makefile in the root of the distribution copies files out of this
directory when creating run directories.  See section~\ref{section:main_make} 
to get more details on the steps to take for a new platform.

Sample scripts for all of the platforms and queuing systems that the
code is commonly run are found in the {\tt Scripts} directory
and are copied into the run directory.
